Scripting
开始
文档
更新日志
隐私
开始
文档
更新日志
隐私
简体中文

读取数量型数据（HealthQuantitySample）

Scripting 应用支持通过全局 API Health.queryQuantitySamples() 查询 HealthKit 中的数量型健康数据，例如步数、心率、体重、卡路里、距离等。

本文将介绍如何使用该 API 查询数据样本并解析结果。

什么是 Quantity Sample？

Quantity Sample（数量型样本） 表示某一时间点或时间段内的数值型健康数据。常见类型包括：

  • stepCount（步数）
  • heartRate（心率）
  • bodyMass（体重）
  • activeEnergyBurned（活动能量消耗）
  • distanceWalkingRunning（步行/跑步距离）

数据样本可能是：

  • 离散数据（单次测量）
  • 累积数据（时间段内累加值）

API 简介

1Health.queryQuantitySamples(
2  quantityType: HealthQuantityType,
3  options?: {
4    startDate?: Date
5    endDate?: Date
6    limit?: number
7    strictStartDate?: boolean
8    strictEndDate?: boolean
9    sortDescriptors?: Array<{
10      key: "startDate" | "endDate" | "count"
11      order?: "forward" | "reverse"
12    }>
13  }
14): Promise<Array<HealthQuantitySample | HealthCumulativeQuantitySample | HealthDiscreteQuantitySample>>

参数说明

参数名 类型 描述
quantityType string 要查询的数据类型，如 "stepCount"、"heartRate"
startDate / endDate Date 查询的时间范围
limit number 限制返回的最大样本数量
strictStartDate / strictEndDate boolean 是否严格匹配开始/结束时间
sortDescriptors Array 对结果进行排序，可按 startDate、endDate 或 count 排序

示例：读取步数数据

1const results = await Health.queryQuantitySamples("stepCount", {
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-02T00:00:00"),
4  limit: 10,
5  sortDescriptors: [{ key: "startDate", order: "reverse" }]
6})
7
8for (const sample of results) {
9  const value = sample.quantityValue(HealthUnit.count())
10  console.log(`步数：${value} 时间：${sample.startDate} ~ ${sample.endDate}`)
11}

示例：读取心率数据（单位为 bpm）

1const results = await Health.queryQuantitySamples("heartRate", {
2  startDate: new Date(Date.now() - 3600 * 1000) // 最近一小时
3})
4
5for (const sample of results) {
6  const bpm = sample.quantityValue(
7    HealthUnit.count().divided(HealthUnit.minute())
8  )
9  console.log(`心率：${bpm} bpm 时间：${sample.startDate}`)
10}

判断样本类型

返回的样本可能属于以下三种之一：

  • HealthQuantitySample（基础类）
  • HealthCumulativeQuantitySample：可调用 .sumQuantity(unit)
  • HealthDiscreteQuantitySample：可调用 .averageQuantity(unit)、.maximumQuantity(unit) 等

你可以使用 in 操作符判断：

1if ("averageQuantity" in sample) {
2  const avg = sample.averageQuantity(HealthUnit.count())
3  console.log("平均值：", avg)
4}

常见类型与推荐单位

数据类型 推荐单位
"stepCount" HealthUnit.count()
"heartRate" HealthUnit.count().divided(HealthUnit.minute())
"bodyMass" HealthUnit.gram(HealthMetricPrefix.kilo)
"activeEnergyBurned" HealthUnit.kilocalorie()
"distanceWalkingRunning" HealthUnit.meter()

错误处理示例

1try {
2  const results = await Health.queryQuantitySamples("stepCount")
3  console.log("共返回样本数量：", results.length)
4} catch (err) {
5  console.error("查询失败：", err)
6}

小结

读取数量型样本的流程如下：

  1. 调用 Health.queryQuantitySamples(类型, 查询参数)
  2. 遍历返回结果
  3. 使用 .quantityValue(unit) 或 .sumQuantity(unit) 等方法获取数值

该 API 提供了对时间序列健康数据的强大访问能力，适用于统计、图表和趋势分析等应用场景。

大纲